Release 10.1A: OpenEdge Data Management:
Database Administration

Creating a structure description file

The structure description file is a text file you prepare that defines the database structure. It contains all of the information required by the PROSTRCT CREATE utility to create a database control area and the database extents.

Use a text editor to create the structure description file. The name you give to the structure description file is usually the name of the database you define, with a .st extension.

The structure description file contains one or more lines of text that provide information about each storage area of the database. Each line of text is composed of tokens, which are text strings made up of alphanumeric characters that describe the following characteristics:

The storage area type.
The area name.
The area number.
Optionally, the records per block.
Optionally, the number of blocks per cluster (for Type II data storage areas only).
The extent pathname.
The extent type.
The extent size.

The following syntax shows how the 8 tokens are combined to form line in a structure description file:

line     = comment | CR | type path [sizeinfo] comment  = * | : | # CR       = blank line type     = a | b | d | t [areainfo]      areainfo = “areaname”[:areanum][,recsPerBlock][;blksPerCluster]            areaname       = string            areanum        = numeric value            recsPerBlock   = numeric value           blksPerCluster = 1 | 8 | 64 | 512 path     = string sizeinfo = extentType size      extentType     = f | v      size           = numeric value > 32

Note: You can comment a .st file and use blank lines. Precede comments with a pound sign (#), colon (:), or asterisk (*).

Table 1–1 explains the value of each of the 8 tokens in a structure description file.

Table 1–1: ST file tokens 

Token	Description
type	Indicates the type of storage area. Possible values are: a — After-image area. b — Before-image area. d — Schema and application data areas. t — Transaction log area.
areaname	Name of the storage area.
areanum	Number of the storage area. Note: If you do not include the area number token, PROSTRCT will assign the area numbers for you. However, if you choose to specify a number for one area in your .st, you must specify area numbers for all the areas or PROSTRCT will return an error.
recsPerBlock	Number of database records in each database block. Valid values are 1, 2, 4, 8, 26, 32, 64, 128, and 256. Notes: This token only applies to areas 7 through 1000. For the schema area, records per block is fixed at 32 for 1K, 2K, and 4K database block sizes, The records per block is 64 for an 8K database block size.
blcksPerCluster	Number of database blocks in each cluster. Possible values are: 1, 8, 64, or 512. Notes: If you leave this value blank, or specify 1, the data area will be Type I. All other values are valid for Type II data areas only. This token only applies to areas 7 through 1000.
path	Absolute or relative pathname of each extent.
extentType	Indicates whether the extent is fixed (f) or variable (v). If the extent type token is not specified, the extent is variable.
size	Size of an extent in kilobytes. This value must be a multiple of 16 times your database block size.

Extent pathnames and naming conventions

The PROSTRCT CREATE utility is designed to allow the end user to specify the minimum amount of information necessary to create a database. Only the area type and extent location must be specified. A suggested convention is that you supply an area name for data storage areas (d). A specific filename or file extension need not be provided. If you specify a pathname, it must represent a standard operating system file. The only pathname restrictions are those that might be imposed by your operating system.

The PROSTRCT CREATE utility will generate filename and file extensions for all database files according to the following naming convention:

The control area (.db) and the log file (.lg) are placed in the directory specified by the command line dbname parameter.
If a relative pathname is provided, including using common dot (.) notation, the relative pathname will be expanded to an absolute pathname. Relative paths begin in your current working directory.
For before-image extents, the filename is the database name with a .bn extension, where n represents the order in which the extents were created, beginning with 1.
For after-image extents, the filename is the database name with a .an extension, where n represents the order in which the extents were created, beginning with 1.
For transaction log extents, the filename is the database name with a .tn extension, where n represents the order in which the extents were created, beginning with 1.
For schema area extents, the filename is the database name with a .dn extension, where n represents the order in which the extents were created and will be used.
For application data area extents, the filename is the database name followed by an underscore and the area number (for example, customer_7.d1). The area number is a unique identifier that differentiates between different areas. The application data area extent filenames also have a .dn extension, where n represents the order in which the extents were created and will be used.
Note: In a structure description (.st) file, to specify a pathname that contains spaces (such as \usr1\misc data), precede the pathname with an exclamation point (!) and wrap the pathname in quotation marks (“ “). For example, !”\usr1\misc data”.

Rules for creating storage areas and extents

When you are defining storage areas and extents in order to create a new database:

The minimum information required in a .st file is one schema area extent definition statement and one primary recovery (BI) area extent definition statement.
The minimum information needed to specify any extent is the storage area type and extent pathname. For example:

# Primary Recovery Area b . # Schema Area d .

If you do not define a primary recovery extent path in the .st file, the PROSTRCT CREATE utility generates an error.

You cannot use any of the reserved storage area names as application data storage area names.

Extent length

You can specify a fixed-length or variable-length extent:

Fixed-length

When you create a fixed-length extent, its blocks are preallocated and preformatted specifically for the database. If you want the extent to be fixed length, the extent type token of the extent description line is f. This token must be lowercase. If the extent is fixed length, use the extent size token to indicate its length in kilobytes.

The size of the extent, in kilobytes, must be a multiple of (16 * database-blocksize). If you specify a size that is not a multiple of this, PROSTRCT CREATE displays a warning message and rounds the size up to the next multiple of (16 * database-blocksize). The minimum length for a fixed-length file is 32K, and the maximum length of a file depends on the size of the file system and the physical volume containing the extent.

Table 1–2 shows how the extent size changes based on the database block size.

Table 1–2: Calculating extent size 

Database block size	Formula	Extent size
1	2*(16 * 1)	32K
	3*(16 * 1)	48K
2	1*(16 * 2)	32K
	2*(16 * 2)	64K
	3*(16 * 2)	96K
4	1*(16 * 4)	64K
	2*(16 * 4)	128K
	3*(16 * 4)	192K
8	1*(16 * 8)	128K
	2*(16 * 8)	256K
	3*(16 * 8)	384K

Variable-length

Typically, you use a variable-length extent as an overflow file when all fixed-length extents have been exhausted. For DB and BI extents, you can define one variable-length extent for each area, and it must be the last extent in the area. There is no limit to the number of variable-length AI extents you can define. While you indicate a variable-length extent by leaving out the extent size in the .st file entry line, you can also specify the maximum size to which the extent can grow by indicating the “v” extent type and a size in kilobytes. The initial allocation for a variable-length extent is 32K or the size of the cluster (whichever is larger). Calculate the cluster size by multiplying your block size times your blocks per cluster value.

Notes: Regardless of whether the extent is fixed- or variable-length, if it is in a data area with clusters its size must be large enough to hold an entire cluster, or PROSTRCT generates and error.

Example structure description file

The following example shows a .st file named sports2000.st that defines a database with:

One primary recovery area.
One schema area.
Three after-image areas each with a fixed-length extent.
One transaction log area with a fixed-length extent used with two-phase commit.
Six application data areas each with one fixed- and one variable-length extent. The area names for the six application data areas are: Employee, Inventory, Cust_Data, Cust_Index, Order, and Misc. Note that the Cust_Data, Cust_Index, and Order areas have cluster sizes assigned to them, and are therefore Type II storage areas. The area numbers are not specified. The areas will be numbered sequentially starting at 7. Blocks per cluster is not specified, creating Type I data areas.

Sample Structure Description File: sports2000.st # # The following defines the Primary Recovery Area consisting of one # variable length extent. It resides in the /usr2/bi directory: # b /usr2/bi # # The following defines the Schema Area consisting of one variable length # extent, residing in the current working directory: # d “Schema Area” . # # The following defines three fixed length After Image Areas each equal to # 1 MB in size: # a /usr3/ai f 1024 a /usr3/ai f 1024 a !”/usr3/ai data” f 1024 # # The following defines a Transaction Log Area equal to 4 MB in size and # residing in the current working directory. This storage area is used # for 2 phase commit: # t . f 4096

# # The following defines six Application Data Areas each with one fixed # length extent equal to 1 MB in size and 1 variable length extent: # d “Employee”,32 /usr1/emp f 1024 d “Employee”,32 /usr1/emp # d “Inventory”,32 /usr1/inv f 1024 d “Inventory”,32 /usr1/inv # d “Cust_Data”,32;64 /usr1/cust f 1024 d “Cust_Data”,32;64 /usr1/cust # d “Cust_Index”,32;8 /usr1/cust f 1024 d “Cust_Index”,32;8 /usr1/cust # d “Order”,32;64 /usr1/ord f 1024 d “Order”,32;64 /usr1/ord # d “Misc”,32 !”/usr1/misc data” f 1024 d “Misc”,32 !”/usr1/misc data” # # Note that the directory pathname for the “Misc” application data area # contains spaces, and to recognize that the pathname is specified with # an ! (exclamation point) and “ “ (quotation marks).

Example structure description file for large files

When creating a new database, large file processing is enabled if the .st file specifies a fixed-length extent size or a maximum size for a variable-length extent that is greater than 2 GB. Large file processing requires an Enterprise database license. The following example shows the .st file of a database with large file processing enabled:

# Sample Structure Description File: largedb.st # # largedb.st to create database largedb with large file processing enabled. # # A fixed length bi file of 1GB and a variable length bi file with a maximum # size of 4GB. # b tests/largedb.b1 f 1048576 b tests/largedb.b2 v 4194304 # # SCHEMA AREA with a fixed length file of 3GB and a variable length file with # a maximum size of 3GB. # d “Schema Area”:6,64 tests/largedb.d1 f 3145728 d “Schema Area”:6,64 tests/largedb.d2 v 3145728 # # TABLE AREA with a fixed length file of just over 2GB and a variable length # file with a maximum size of 1TB. # d “Table Area”:7,64 tests/largedb_7.d1 f 2097280 d “Table Area”:7,64 tests/largedb_7.d2 # # A fixed length ai file of 2GB and a variable length file with a maximum size # of 1TB. a tests/largedb.a1 f 2097152 a tests/largedb.a2 #

For more information on enabling large file processing, see the "PROUTIL ENABLELARGEFILES qualifier" section.